fix(gax): propagate structured LRO error details to ApiException by nnicolee · Pull Request #14022 · googleapis/google-cloud-java

nnicolee · 2026-08-10T03:53:58Z

Description:

When a Long-Running Operation (LRO) completes with a failure, structured error details inside the operation's error payload were previously dropped. This made it impossible for client applications to access fine-grained provider error messages (such as quota or usage violations) via the public ApiException.getErrorDetails() API.

This PR implements Phase 1 of the LRO error propagation design by establishing the transport-agnostic mechanism to propagate structured LRO error details in GAX for both gRPC and HTTP/JSON (REST) transports.

Design doc: go/sdk:java-lro-error-details

Key Changes:

Core GAX Interfaces:
- Added support to fetch structured error details from the LRO operation snapshots.
gRPC Transport:
- Implemented error details extraction from LRO operation error payloads (only populated if structured error details are present).
- Updated the gRPC response transformer to pass these error details when converting failed operations into exception objects.
- Added unit test validation checking details propagation for LRO failures over gRPC.
HTTP/JSON (REST) Transport:
- Implemented error details extraction and storage in REST LRO operation snapshots (only populated if structured error details are present).
- Updated the REST response transformer to fetch and pass the snapshot's error details.
- Added unit test validation checking details propagation for LRO failures over HTTP/JSON.
Integration & Unit Testing:
- Added a Showcase integration test verifying successful end-to-end propagation of error details over gRPC.
- Note on HTTP/JSON Integration Test: Deferring the end-to-end Showcase integration test for HTTP/JSON LROs to Phase 2 because HTTP/JSON relies on a TypeRegistry in generated stubs to parse custom/standard payload types packed in Any details, the test client fails to deserialize these details. Once we roll out the generator changes in Phase 2 to automatically add error details types to generated stub registries, the Showcase REST integration test will pass out-of-the-box. We have added unit tests to cover the HTTP/JSON LRO response parsing pathway in the interim.

Testing:

Verified that all gRPC and HTTP/JSON transformer unit tests pass successfully:
mvn test -pl sdk-platform-java/gax-java/gax-grpc,sdk-platform-java/gax-java/gax-httpjson -Dtest=ProtoOperationTransformersTest
Verified that the Showcase LRO integration test passes successfully:
mvn test -pl java-showcase/gapic-showcase -Dtest=ITLongRunningOperation

gemini-code-assist

Code Review

This pull request adds support for propagating error details in long-running operations (LRO) for both gRPC and HTTP/JSON transports. This is achieved by adding getErrorDetails() to the OperationSnapshot interface and implementing it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. The ProtoOperationTransformers are updated to pass these error details when throwing exceptions, and corresponding integration and unit tests are added. Feedback on the changes includes renaming a misleadingly named test that asserts error propagation rather than dropping, and ensuring that ErrorDetails is only instantiated and returned in GrpcOperationSnapshot and HttpJsonOperationSnapshot if there are actual details present (i.e., checking that the details count is greater than zero).

nnicolee · 2026-08-10T04:23:39Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for propagating error details from long-running operations (LROs) across both gRPC and HTTP/JSON transports by introducing a getErrorDetails() method to the OperationSnapshot interface and implementing it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. It also updates ProtoOperationTransformers to pass these error details when throwing exceptions and adds corresponding integration and unit tests. Feedback on the changes highlights a potential issue in HttpJsonOperationSnapshot.Builder.setOperation where errorDetails is not reset to null if the operation has no error, which could lead to stale state if the builder is reused.

nnicolee · 2026-08-10T14:03:31Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for propagating error details in long-running operations (LRO) for both gRPC and HTTP/JSON transports. It introduces the getErrorDetails() method to the OperationSnapshot interface and implements it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. Additionally, it updates the ProtoOperationTransformers to include these error details when constructing exceptions, and adds corresponding unit and integration tests. The reviewer suggested adding a timeout to the operationFuture.get() call in the new integration test to prevent the test suite from hanging indefinitely.

lqiu96 · 2026-08-10T15:32:47Z

+  default @Nullable ErrorDetails getErrorDetails() {
+    return null;
+  }


qq, what do you think about returning a non-null empty ErrorDetails instead of null here? I think this would be similar to the proto messages where there is a default value.

IIUC, this is primarily used within ProtoOperationTransformers's ResponseTransformer which operations on a response and it should return Status.getDefaultInstance() if there is no error

great suggestion! this would aligns more with the proto messages! I have updated the interface to return an empty ErrorDetails rather than null!

lqiu96 · 2026-08-10T19:52:50Z

+     * @param errorDetails the LRO error details
+     * @return the builder instance
+     */
+    public Builder setErrorDetails(final @Nullable ErrorDetails errorDetails) {


nit: this is only for testing right? If so, can we make this package-private and enforce that ErrorDetails cannot be nullable?

One other question with this: I don't think I see a gRPC variant for this. Do we need to expose this setter?

yes, this is only used for unit testing inside com.google.api.gax.httpjson. I have updated setErrorDetails to be package-private and non-nullable. The gRPC snapshot class (GrpcOperationSnapshot) is package-private and doesn't use a builder (it is constructed via the static create(Operation) factory), which is why it doesn't have a setter!

lqiu96 · 2026-08-10T19:53:54Z

+    if (operation.hasError() && operation.getError().getDetailsCount() > 0) {
+      return ErrorDetails.builder()
+          .setRawErrorMessages(operation.getError().getDetailsList())
+          .build();
+    }
+    return ErrorDetails.builder().setRawErrorMessages(Collections.emptyList()).build();


Do we need the if block here? Can we just do something like

ErrorDetails.builder().setRawErrorMessages(operation.getError().getDetailsList()).build();?

yes! since it returns an empty list by default, we can construct this directly, updated!

lqiu96 · 2026-08-10T19:55:02Z

@@ -193,4 +199,35 @@ void testHttpJson_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineExce
          TestClientInitializer.AWAIT_TERMINATION_SECONDS, TimeUnit.SECONDS);
    }
  }
+
+  @Test
+  void testGRPC_LROErrorResponse_propagatesErrorDetails() throws Exception {


I know parsing HttpJson is a bit more involved/ difficult since we need to manually unpack the Any proto. Would it be possible to also add a HttpJson variant as well?

Added testHttpJson_LROErrorResponse_propagatesErrorDetails!

to support this, I made ProtoRestSerializer.create(TypeRegistry) public in gax-httpjson so that stubs can serialize custom Any fields in requests, and registered PoetryError in HttpJsonEchoStub's static type registry so the serialization of the wait request body succeeds!

lqiu96 · 2026-08-10T20:00:25Z

+  void testGRPC_LROErrorResponse_propagatesErrorDetails() throws Exception {
+    EchoClient grpcClient = TestClientInitializer.createGrpcEchoClient();
+    try {
+      PoetryError poetryError =
+          PoetryError.newBuilder().setPoem("Roses are red, violets are blue").build();
+      Status status =
+          Status.newBuilder()
+              .setCode(Code.ALREADY_EXISTS_VALUE)
+              .setMessage("The resource already exists")
+              .addDetails(Any.pack(poetryError))
+              .build();


nit: I know we're blocking on the ErrorDetails Showcase test. I think these tests may be better suited in that file. Let's have this live here for now and then we can move it over there in the future.

sounds good, will move them later once the PRs become unblocked!

sonarqubecloud · 2026-08-11T05:05:45Z

Quality Gate passed for 'gapic-generator-java-root'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
80.0% Coverage on New Code
2.9% Duplication on New Code

See analysis details on SonarQube Cloud

sonarqubecloud · 2026-08-11T05:07:28Z

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

feat(gax): propagate structured LRO error details to ApiException

97672a9

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

nnicolee added 2 commits August 10, 2026 04:07

fix: updated http/json snapshot to adhere to monorepo styling

5329849

fix: updated following gemini feedback

f6913df

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread ...x-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonOperationSnapshot.java

added else block to prevent stale errorDetails

5607dae

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread ...case/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITLongRunningOperation.java

nnicolee marked this pull request as ready for review August 10, 2026 14:21

nnicolee requested review from a team as code owners August 10, 2026 14:21

nnicolee requested a review from lqiu96 August 10, 2026 14:21

lqiu96 reviewed Aug 10, 2026

View reviewed changes

Comment thread ...java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ProtoOperationTransformers.java

nnicolee added 2 commits August 10, 2026 17:55

updated to return nonnull empty ErrorDetails

0fbf1ba

added missing import

7e2c12b

diegomarquezp approved these changes Aug 10, 2026

View reviewed changes

lqiu96 reviewed Aug 10, 2026

View reviewed changes

Comment thread ...x-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonOperationSnapshot.java

lqiu96 reviewed Aug 10, 2026

View reviewed changes

Comment thread ...form-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcOperationSnapshot.java

lqiu96 reviewed Aug 10, 2026

View reviewed changes

nnicolee and others added 2 commits August 11, 2026 04:53

address PR comments and add http/json lro error integration test

afec21c

Merge branch 'main' into feat/lro-generic-error-propagation

ca4a998

Uh oh!

Conversation

nnicolee commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

Key Changes:

Testing:

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nnicolee commented Aug 10, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

nnicolee commented Aug 10, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Aug 11, 2026

Quality Gate passed for 'gapic-generator-java-root'

Uh oh!

sonarqubecloud Bot commented Aug 11, 2026

Quality Gate failed for 'gapic-generator-java-root'

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nnicolee commented Aug 10, 2026 •

edited

Loading